home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / spawno30.zip / SPAWNO.DOC < prev    next >
Text File  |  1990-11-16  |  8KB  |  184 lines
  1. SPAWNO v3.0    11/16/90      disk/EMS/XMS swapping replacement for spawn()
  2. (c) Copyright 1990 Ralf Brown.    All Rights Reserved.
  3.  
  4. LICENSE
  5.  
  6. This document and the associated header file, libraries, and object
  7. modules may be freely copied provided that:
  8.      1) all of the files are copied as a group (such as in a single
  9.     archive).  See below for a list of files.
  10.      2) the files are not modified in any way (including removal or
  11.     alteration of copyright notices or this license)
  12.      3) no charge beyond a cost-recovery fee not to exceed $5 is made
  13.  
  14. I would appreciate a brief mention in your documentation if you
  15. distribute a program which incorporates SPAWNO.
  16.  
  17. DISCLAIMER
  18.  
  19. Although both I and others have tested the code which comprises SPAWNO,
  20. it is entirely possible that SPAWNO may malfunction in environments or
  21. under circumstances in which it has not been tested.  This code is
  22. provided AS IS, and the author disclaims any and all responsibility for
  23. damages (both consequential and incidental) resulting from the use or
  24. misuse of SPAWNO.  Sole responsibility for determining the suitability
  25. of the code rests with the user.
  26.  
  27.  
  28. -----------------
  29. FILES
  30.  
  31. The disk or archive you received should contain the following files:
  32.  
  33.     SPAWNO.DOC    this file
  34.     SPAWNO.H    the header file providing prototypes for the functions
  35.     SPAWN_TC.ZIP    archive containing Turbo C/C++ versions of the
  36.             libraries SPAWNx.LIB for each of [T]iny, [S]mall,
  37.             [C]ompact, [M]edium, and [L]arge memory models.
  38.     SPAWN_MS.ZIP    archive containing SPAWNx.LIB for Microsoft C
  39.     *.C        source for the spawn...o() functions
  40.     SPAWNPTH.ASM    source for the path search
  41.  
  42. (sorry, I'm not releasing source for the actual swapper at this time)
  43.  
  44.  
  45. -----------------
  46. INSTRUCTIONS
  47.  
  48. Include the header file SPAWNO.H (after PROCESS.H if you include that
  49. file).    Then use the functions provided in this archive--spawnvo(),
  50. spawnlo(), spawnvpo(), etc--as you would the corresponding spawnv(),
  51. spawnl(), etc, except replace the first argument by a string containing
  52. the path where the swap file is to be stored.  Note that the swap file
  53. path is required even when swapping to XMS or EMS, as SPAWNO will swap
  54. to disk anyway if there is not enough XMS or EMS memory available.
  55.  
  56. The spawn?p?o() functions search for both .COM and .EXE files in the
  57. current directory and then in the pathed directories if no extension is
  58. given, but use the specified extension if present.  If a full pathname
  59. is given to those functions, only the specified directory is searched.
  60.  
  61. If you define the preprocessor macros REPLACE_SPAWN and OVERLAY_PATH
  62. before #including SPAWNO.H, you should be able to use these functions
  63. with existing code with minimal changes.  See SPAWNO.H for more details.
  64.  
  65. When linking, you must include SPAWNx.LIB.  A sample TCC line would
  66. be
  67.  
  68.     tcc -mc <other-flags> sample spawnc.lib library.lib
  69.  
  70. This results in 448 bytes (disk/XMS) or 464 bytes (EMS) remaining in
  71. memory while the spawned program executes.  However, if you want to keep
  72. an interrupt hooked which might be invoked while spawned, you must set
  73. __spawn_resident large enough that *all* code and data which could be
  74. invoked by that interrupt is kept resident[1].    You must also ensure
  75. that none of the code used by interrupt handlers while spawned is
  76. located in the first 224 bytes of the executable (which are temporarily
  77. destroyed while spawning).  SPAWNO automatically deactivates INT 23h and
  78. INT 24h and restores them before returning to the caller.
  79.  
  80. Note: there are two separate sets of libraries, one for Turbo C/C++ (in
  81. the archive SPAWN_TC.ZIP), the other for Microsoft C (in SPAWN_MS.ZIP).
  82. Extract only the version you need, as both sets of files have the same
  83. names.
  84.  
  85. [1] Due to the segment layout used by C compilers, this option is probably
  86.     useful only when calling SPAWNO from assembly-language code (which can
  87.     localize such code and data near the start of the executable) or a
  88.     small program which uses a large amount of space in the far heap.
  89.  
  90.  
  91. -----------------
  92. LIMITATIONS
  93.  
  94. The Turbo C version of SPAWNO only swaps out the memory block initially
  95. allocated to the program.  If you cause additional memory blocks to be
  96. allocated (such as with allocmem()), the additional blocks are not
  97. swapped out. In that case, you will need to use the Microsoft C version
  98. of SPAWNO, which does swap out all memory blocks belonging to the
  99. program.  Note that while the Microsoft version works correctly with
  100. Turbo C, the errno variable will not be set to the proper symbolic
  101. constant on error (though it will be nonzero).    The Microsoft version of
  102. SPAWNO will increase the size of the executable by about 1K compared to
  103. the Turbo C version.
  104.  
  105. If the program's environment is large enough that the copy DOS makes
  106. will overwrite the entire code segment and the initialized data segment,
  107. SPAWNO will probably fail, as the name of the program to spawn could be
  108. overwritten before DOS uses it.  This should not be a problem in
  109. practice, since a program small enough that it is likely to encounter an
  110. environment large enough to cause the problem won't gain much from
  111. SPAWNO anyway.
  112.  
  113. There is a chance that this code will not work under the upcoming MSDOS 5,
  114. as it assumes that DOS does not store any internal information beyond offset
  115. 3Fh in the PSP (versions through 4.02 do not store data beyond offset 3Bh).
  116.  
  117.  
  118. -----------------
  119. SUPPORT
  120.  
  121. Since I am not getting any money, I can't promise any support.  I have
  122. too much to do as it is....
  123.  
  124.  
  125. -----------------
  126. ACKNOWLEDGEMENTS
  127.  
  128. Thanks to Gene McManus for testing the Microsoft version of SPAWNO 3.0.
  129.  
  130.  
  131. -----------------
  132. Functions:
  133.     int spawnvo(const char *overlay_path, const char *name,
  134.             const char **args) ;
  135.     int spawnvpo(const char *overlay_path, const char *name,
  136.              const char **args) ;
  137.     int spawnveo(const char *overlay_path, const char *name,
  138.              const char **args,const char **env) ;
  139.     int spawnvpeo(const char *overlay_path, const char *name,
  140.              const char **args,const char **env) ;
  141.     int spawnlo(const char *overlay_path, const char *name, ...) ;
  142.     int spawnlpo(const char *overlay_path, const char *name, ...) ;
  143.     int spawnleo(const char *overlay_path, const char *name, ...) ;
  144.     int spawnlpeo(const char *overlay_path, const char *name, ...) ;
  145.  
  146. Global variables:
  147.        char __spawn_xms ;  /* 0 = don't use XMS memory for swapping */
  148.                /* 1 = use XMS if available */
  149.                /* (default 1) */
  150.        char __spawn_ems ;  /* 0 = don't use EMS memory for swapping */
  151.                /* 1 = use EMS if available and no XMS */
  152.                /* (default 1) */
  153.        unsigned __spawn_resident ; /* number of paragraphs to keep resident */
  154.                    /* while in the child program */
  155.                    /* (default 0 = minimum possible) */
  156.  
  157. External functions called by SPAWNO:
  158.     void *malloc(int) ;
  159.     void free(void *) ;
  160.     int strlen(char *) ;
  161.     int pascal __IOERROR(int) ; /* Turbo C only--internal run-time func */
  162.  
  163. External variables used by SPAWNO:
  164.     int errno ;
  165.     int _doserrno ;
  166.     unsigned int _psp ;
  167.  
  168. Other:
  169.     SPAWNO version overwrites the PSP, so the commandline will
  170.     be lost unless it was copied before the first spawn().
  171.  
  172.  
  173. -----------------
  174. Send comments, bug reports, etc. to
  175.  
  176.      Internet: ralf@cs.cmu.edu
  177.      Fidonet:  Ralf Brown 1:129/3.1 (or post to DR_DEBUG--I can't reply to
  178.                      netmail from outside Zone 1 at this time)
  179. or
  180.      Ralf Brown
  181.      School of Computer Science
  182.      Carnegie Mellon University
  183.      Pittsburgh, PA 15213-3890
  184.